.\"****************************************************************************
.\" Written by Chris Dunlap <cdunlap@llnl.gov>.
.\" Copyright (C) 2007-2013 Lawrence Livermore National Security, LLC.
.\" Copyright (C) 2002-2007 The Regents of the University of California.
.\" UCRL-CODE-155910.
.\"
.\" This file is part of the MUNGE Uid 'N' Gid Emporium (MUNGE).
.\" For details, see <https://munge.googlecode.com/>.
.\"
.\" MUNGE is free software: you can redistribute it and/or modify it under
.\" the terms of the GNU General Public License as published by the Free
.\" Software Foundation, either version 3 of the License, or (at your option)
.\" any later version.  Additionally for the MUNGE library (libmunge), you
.\" can redistribute it and/or modify it under the terms of the GNU Lesser
.\" General Public License as published by the Free Software Foundation,
.\" either version 3 of the License, or (at your option) any later version.
.\"
.\" MUNGE is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" and GNU Lesser General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" and GNU Lesser General Public License along with MUNGE.  If not, see
.\" <http://www.gnu.org/licenses/>.
.\"****************************************************************************

.TH MUNGE 7 "@META_DATE@" "@META_ALIAS@" "MUNGE Uid 'N' Gid Emporium"

.SH NAME
munge \- MUNGE overview

.SH INTRODUCTION
MUNGE (MUNGE Uid 'N' Gid Emporium) is an authentication service for creating
and validating credentials.  It is designed to be highly scalable for use
in an HPC cluster environment.  It allows a process to authenticate the
UID and GID of another local or remote process within a group of hosts
having common users and groups.  These hosts form a security realm that is
defined by a shared cryptographic key.  Clients within this security realm
can create and validate credentials without the use of root privileges,
reserved ports, or platform-specific methods.

.SH RATIONALE
The need for MUNGE arose out of the HPC cluster environment.  Consider the
scenario in which a local daemon running on a login node receives a client
request and forwards it on to remote daemons running on compute nodes within
the cluster.  Since the user has already logged on to the login node, the
local daemon just needs a reliable means of ascertaining the UID and GID
of the client process.  Furthermore, the remote daemons need a mechanism
to ensure the forwarded authentication data has not been subsequently altered.
.PP
A common solution to this problem is to use Unix domain sockets to determine
the identity of the local client, and then forward this information on to
remote hosts via trusted rsh connections.  But this presents several new
problems.  First, there is no portable API for determining the identity of
a client over a Unix domain socket.  Second, rsh connections must originate
from a reserved port; the limited number of reserved ports available on a
given host directly limits scalability.  Third, root privileges are required
in order to bind to a reserved port.  Finally, the remote daemons have no
means of determining whether the client identity is authentic.

.SH USAGE
A process creates a credential by requesting one from the local MUNGE
service, either via the \fBmunge_encode\fR() C library call or the
\fBmunge\fR executable.  The encoded credential contains the UID and GID of
the originating process.  This process sends the credential to another process
within the security realm as a means of proving its identity.  The receiving
process validates the credential with the use of its local MUNGE service,
either via the \fBmunge_decode\fR() C library call or the \fBunmunge\fR
executable.  The decoded credential provides the receiving process with a
reliable means of ascertaining the UID and GID of the originating process.
This information can be used for accounting or access control decisions.

.SH DETAILS
The contents of the credential (including any optional payload data)
are encrypted with a key shared by all \fBmunged\fR daemons within the
security realm.  The integrity of the credential is ensured by a message
authentication code (MAC).  The credential is valid for a limited time defined
by its time-to-live (TTL); this presumes clocks within a security realm are
in sync.  Unexpired credentials are tracked by the local \fBmunged\fR daemon
in order to prevent replay attacks on a given host.  Decoding of a credential
can be restricted to a particular user and/or group ID.  The payload data
can be used for purposes such as embedding the destination's address to
ensure the credential is only valid on a specific host.  The internal
format of the credential is encoded in a platform-independent manner.
And the credential itself is base64 encoded to allow it to be transmitted
over virtually any transport.

.SH AUTHOR
@META_AUTHOR@

.SH COPYRIGHT
Copyright (C) 2007-2013 Lawrence Livermore National Security, LLC.
.br
Copyright (C) 2002-2007 The Regents of the University of California.
.PP
MUNGE is free software: you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.
.PP
Additionally for the MUNGE library (libmunge), you can redistribute it
and/or modify it under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation, either version 3 of the License,
or (at your option) any later version.

.SH "SEE ALSO"
.BR munge (1),
.BR remunge (1),
.BR unmunge (1),
.BR munge (3),
.BR munge_ctx (3),
.BR munge_enum (3),
.BR munged (8).
.PP
\fBhttps://munge.googlecode.com/\fR
